home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / NEWSOFT / OCTOBER / PCLTOOLS / ASC2PCL / A2P.man next >
Text File  |  1997-10-12  |  11KB  |  284 lines
  1. ASC2PCL
  2. =======
  3.  
  4.  
  5. A tool to convert ASCII text to PCL (HP Laserjet) or ASCII (i.e. just use
  6. the search-and-replace engine).
  7.  
  8. You can print the text in various (user-definable) formats, for instance
  9. 2 up landscape. You may use any of the printer-resident fonts and use
  10. ASC2PCL's powerful search-and-replace engine, enabling you for instance
  11. to print C code context-sensitive (similar to Zap's coloured C mode).
  12.  
  13.  
  14. USAGE:
  15. ------
  16.  
  17. asc2pcl [switches] <infile> [<outfile>]
  18.  
  19. If no <outfile> is given output is directed to the file "printout".
  20.  
  21.  
  22. SWITCHES:
  23. ---------
  24.  
  25. -c x        specify characters per line (more precisely: characters with
  26.         magnification 1.0) (default: 80)
  27.  
  28. -d x        print every x-th page, default 1 (i.e. every page). The count
  29.         is always relative to the first page printed.
  30.  
  31. -e x        encoding number (default 2 - Latin 1)
  32.  
  33. -f x        x = first page
  34.  
  35. -h x        x = file with search/replace patterns (see below)
  36.  
  37. -i x        x = file with font definitions (see below)
  38.  
  39. -l x        x = last page
  40.  
  41. -m x        x = file with format definitions
  42.  
  43. -n        print line numbers (will effectively shrink line width (by 10 chars))
  44.  
  45. -o0,-o1,-o2     Mode: 0 (PCL, default), 1(ASCII), 2(TEST)
  46.  
  47. -p x        x = number of format to use for this print job (default is 1,
  48.         i.e. 2 columns, landscape with the default formats).
  49.  
  50. -r x        x = resolution in dpi
  51.  
  52. -s x        x = promilles of font height to use for linefeeds
  53.         (default 1500, i.e. linefeed = 3/2 font height)
  54.  
  55. -t x        x = width of tab columns in characters. I.e. with the
  56.         default value of 8 a tab command will move the "cursor"
  57.         to the next character position that's a multiple of 8.
  58.  
  59. -v x        verbose mode; x = bitfield. Meaning of bits 0,1,2:
  60.         0: Show fonts, 1: Show Formats, 2: Show encodings
  61.  
  62. -w        switch wordwrap mode on (default off). If off lines
  63.         are broken as soon as the line width exceeds the maximum
  64.         (see -c). Otherwise it's broken at the last space,
  65.         comma and a range of similar characters that preceded this
  66.         place.
  67.  
  68. -z x        bitfield for specials; meaning of bits 0,1:
  69.  
  70.         0: automatic linefeed off. By default each line of the
  71.            input file becomes a line in the output file. If this
  72.            bit is set you have to explicitly specify linefeed
  73.            characters (see search-and-replace patterns).
  74.         1: font styles and weights are taken from the last valid
  75.            mode even if they're zero (default: take only if non-zero).
  76.            (see search-and-replace patterns).
  77.  
  78.  
  79. EXAMPLE:
  80. ========
  81.  
  82. asc2pcl -w -h rep_C -f 2 -l 5 c.foo xyz
  83.  
  84. Print the file c.foo in wordwrap mode (-w) using search-and-replace patterns from
  85. the file rep_C, print pages 2 to 5 only and print into file <xyz>.
  86.  
  87.  
  88.  
  89. FONTS
  90. -----
  91.  
  92. Fonts are referenced by their number (internal ASC2PCL numbers, the numbers of the
  93. default fonts are 0,...,7; for an overview see the file Fonts_LJ5). You can have up
  94. to 64 fonts defined (numbers 0,...,63).
  95. Font numbers 64,...,127 have special meaning. They refer to fonts 0,...,63 (i.e.
  96. just subtract 64) but the fonts are forced to be monospaced (which of course only
  97. makes a difference with proportionally spaced fonts). So for instance font number
  98. 68 means font number 4, but force monospacing.
  99. Using it on proportionally spaced fonts might be useful sometimes but let me warn
  100. you that it can look rather weird...
  101. A font number of -1 means no (new) font.
  102.  
  103.  
  104.  
  105. SCALING FACTORS
  106. ---------------
  107.  
  108. Scaling factors are relative to the default font size (width of current rectangle
  109. divided by the number of characters per line) in promilles (i.e. 1000 -> 1.0). The
  110. names I use have the meaning:
  111.  
  112. scale    determines how large a font the printer should use. Proportional-spaced fonts
  113.     usually should be scaled to 1.5 the size a monospaced font would have.
  114.  
  115. scalex
  116. scaley    determine what size per character ASC2PCL should assume (this is completely
  117.     independent of scale). This determines how many characters will fit on a
  118.     line and how many lines on a page.
  119.  
  120.  
  121.  
  122. SEARCH AND REPLACE PATTERNS FILE
  123. --------------------------------
  124.  
  125. The general format is explained in the file rep_C, which does context-sensitive
  126. C/C++ printing. So here's just additional info:
  127. First up you can specify up to 255 modes. These each have their own fonts
  128. defined (or -1 for none) and scaling factors in promilles relative to the font size
  129. actually used. "scale" is the amount to magnify the font by (relevant for the printer
  130. only), "scalex", "scaley" are the relative sizes ASC2PCL should assume (i.e. if you
  131. gave a scalex factor of 500 (=0.5) you'd get twice as many characters on a line). By
  132. default mode 1 is on. Modes are internally numbered from 1 in the order they were
  133. defined in the file.
  134. The font to actually use is determined by scanning through the active modes. The
  135. last one that has a valid font defined wins. The same applies for style and weight
  136. (see also the -z switch). You may have to take this into account if you allow
  137. more than one active mode at any time; the higher the mode's number the higher
  138. its priority.
  139. Each search and replace pattern must have a mode exception list. This is a list
  140. of modes which automatically invalidate the search. If the first character in the
  141. mode exception list is a '!' the mode exception list becomes a mode required list
  142. (i.e. don't except for modes ...).
  143. You may use any printable character but '\' (backlash). That one's used as an
  144. escape character for commands and has to be quoted if you wish to use it (i.e.
  145. if you want to search for "\" you have to write "\\").
  146. Each search is limited to ONE LINE OF THE INPUT FILE! You can't scan over multiple
  147. lines.
  148. Each line starts with 0 and ends with 0. So if you want to search for "foo" at the
  149. beginning of a line you use \&00foo, if you look for this at the end of lines you
  150. use foo\&00. DON'T INSERT A \&00 VIA THE REPLACE STRING (you'll notice that in rep_C
  151. I have a seperate search string for a function at the beginning of a line; that's
  152. to avoid the \&00 being inserted in the replace string along with the other prefixes.).
  153.  
  154. Each search string must start with a fixed character (otherwise searching with
  155. many patterns would take forever). To avoid having to write lots of basically
  156. identical search strings you may give a list of prefixes (i.e. the first characters)
  157. which can be referenced as '\0' in the search and the replace string. E.g. a prefix
  158. list of {a,b,C-F} and a search string of \0foo will create search patterns for
  159. afoo, bfoo, Cfoo, Dfoo, Efoo and Ffoo.
  160.  
  161. For identical prefix characters the search patterns that were defined earlier in the
  162. file will be tried first. The main aspect where this is important is in the case of
  163. mode exceptions where you search for the same string but replace it with different
  164. strings depending on the current mode setup. You might for instance want to use
  165. replace pattern 1 if modes A,B,C are off, else pattern 2 if modes B,C are off else
  166. pattern 3 if mode C is off. For this define pattern 1 first, then 2 then 3.
  167.  
  168. Unless you intend to run the program in -z 2 mode you should never specify linefeed
  169. characters (\&0a) in your replace string. Don't ever specify \&00. In -z 2 mode
  170. text from the input file is read until the line is full or a linefeed was inserted
  171. via a replace string; so this mode is useful if you wish to completely reformat
  172. your input text (for instance printing stuff written at 40 chars per line at 80
  173. chars per line) whereas otherwise each line of the input file becomes a line in
  174. the output file (good for source code printing).
  175.  
  176. Any characters in the range of 0-31 which aren't part of a found sequence will
  177. be eliminated. So if you e.g. want to retain tabs (\&09) you must replace them with
  178. themselves.
  179.  
  180. The offset number tells ASC2PCL by how much it should increase the current position
  181. in the line after it has found this pattern. The best way to explain this is an
  182. example (from rep_C):
  183. When searching for functions I look for the characters ' ', '(', and so on, followed
  184. by at least one of the characters a-zA-Z0-9_, any number of spaces/tabs and an
  185. opening bracket. Now this opening bracket could be the prefix for a following
  186. function; so after I found a function I have to go back 1 position in the line
  187. (increase by -1) so I can see if that bracket is starting another function. Note that
  188. in this case you mustn't include the function's opening bracket in the replace string
  189. since otherwise it would appear twice.
  190.  
  191.  
  192. Search string:
  193. --------------
  194.  
  195. Commands:
  196.  
  197. *    any character; e.g. abc*def would match anything that starts with abc and
  198.     ends with def.
  199. \&xx    character with hex-code xx, e.g. \&2a for '*'.
  200. \*    arbitrary repetition of preceding structure/character. E.g. d\* means
  201.     any number of d's.
  202. \+    Case sensitive mode on (default off)
  203. \-    Case sensitive mode off
  204. \[    Opening bracket for range. If the first character is a '!' this means
  205.     any but the specified characters, otherwise only the specified characters.
  206.     You may use '-' to specify a continuous range; if you wish to allow the
  207.     character '-' you have to use \&2d. Examples: \[a-z.,\] (the letters a
  208.     through z, '.' and ','), \[!0-9\] (everything but the numbers 0 through 9).
  209.     The contents of a range bracket are always case sensitive!
  210. \]    closing bracket for range.
  211. \|    OR command, e.g. xxx\|yyy. You should only use this in a \(...\) environment.
  212. \(    opening bracket for subexpression. E.g. \(xxx\|yyy\) (xxx OR yyy),
  213.     \(xyz\)\* (any repetition of xyz). The contents of the bracket shouldn't end
  214.     in a '*' or a "\*" (will be ignored).
  215. \)    closing bracket for subexpression.
  216. \{    start of argument for future reference (see \1,...,\9 in Exception / Replace
  217.     String). This must never occurr within another \{...\} or \(...\).
  218. \}    end of argument.
  219. \n    end of line (gets translated to 0)
  220. \0    one of the prefixes given in the prefix list (see above).
  221.  
  222. Exception string:
  223. -----------------
  224.  
  225. This is a string of the format \#abc\#def... where '#' is any number from 1 through 9,
  226. giving the number of the argument and the following string up to the next '\' (or end
  227. of the string) is the string this argument must not be. For instance basically C's
  228. "if (...", "while (..." and so on look exactly like functions to the program but I
  229. don't wanna print them as such. Therefore the exception list.
  230.  
  231.  
  232. Replace string:
  233. ---------------
  234.  
  235. Commands:
  236.  
  237. \1,...,\9    insert argument \1,...,\9
  238. \&xx        see Search String
  239. \m{mode}    increase count of <mode>. Up to 127 is possible (I really hope no one
  240.         will need more than this...) A mode is active if it has a count of
  241.         at least 1. By default mode 1 is on (1).
  242. \M{mode}    decrease count of <mode>
  243.  
  244.  
  245. FONT DEFINITION FILE
  246. --------------------
  247.  
  248. To define the printer resident fonts. Just check out the file "Fonts_LJ5".
  249.  
  250.  
  251. FORMAT DEFINITIONS FILE
  252. -----------------------
  253.  
  254. To define page formats. Check out the file "Formats" for more info.
  255.  
  256. Commands in the headline/footline:
  257.  
  258. \c    Center printing; may look funny if you're not using a monospaced font at
  259.     magnification 1.0
  260. \r    Print right-aligned. May look funny...
  261. \#    Page number
  262. \f    Input file
  263.  
  264.  
  265.  
  266.  
  267.  
  268. THIS PROGRAM IS FREEWARE. YOU MAY COPY IT FREELY AS LONG AS NO PART OF IT
  269. IS CHANGED AND IT'S NOT SOLD FOR PROFIT. I RETAIN THE COPYRIGHT.
  270. I WILL NOT ACCEPT ANY RESPONSIBLITY FOR ANY DAMAGES CAUSED BY THE USE OF
  271. THIS PROGRAM, IMPLICITLY OR EXPLICITLY. USE IT ENTIRELY AT YOUR OWN RISK.
  272.  
  273.  
  274. Have fun,
  275.  
  276.  
  277.  
  278. Andreas Dehmel
  279. Am Schorn 18
  280. 82327 Tutzing
  281. Germany
  282.  
  283. dehmel@forwiss.tu-muenchen.de
  284.